home *** CD-ROM | disk | FTP | other *** search
/ Workbench Design / WB Collection.iso / workbench werkzeuge / uhren & terminkalender / time / tolleuhr / tolleuhr.guide (.txt) < prev    next >
Amigaguide Document  |  1996-04-07  |  15KB  |  303 lines
  1. @database TolleUhr.guide
  2. @$VER: TolleUhr.guide 1.31 (17.11.95)
  3. This is a document in the AmigaGuide format. To read it, use either
  4. AmigaGuide, MultiView, or any other AmigaGuide compatible hypertext
  5. browser.
  6. @node main "TolleUhr Documentation - Contents"
  7.                           TolleUhr 1.31
  8.                 written in 1993/94 by Matthias Fleischer
  9.                   enhanced in 1994/95 by Gunther Nikl
  10.                          Public Domain
  11.    @{" Introduction     " link Introduction}                  What is TolleUhr?
  12.    @{" Requirements     " link Requirements}                  What system do I need?
  13.    @{" Installation     " link Installation}                  Getting started
  14.    @{" Usage            " link Usage}                  All available options
  15.    @{" Known bugs       " link Bugs}                  What does not work?
  16.    @{" Technical stuff  " link Source}                  About the Source
  17.    @{" History          " link History}                  What is new in this version?
  18.    @{" Acknowledgments  " link Acknowledgments}                  Who I want to thank.
  19.    @{" Disclaimer       " link Disclaimer}                  Short: Use it at your own risk!
  20.    @{" Copyright        " link Copyright}                  About legal issues.
  21.    @{" Author           " link Author}                  Where you can reach me.
  22. @endnode
  23. @node Introduction "TolleUhr Documentation - Introduction"
  24. Introduction
  25. ************
  26. This is yet another Workbench-Clock-Utility ???!!?! Not quite :-)
  27. TolleUhr is an analogous clock for the workbench (or any other public
  28. screen) and looks really nice.
  29. The functionality in short:
  30.   - nice outfit
  31.   - mini-menu
  32.   - cli && workbench support
  33.   - optional second hand
  34.   - custom background-pattern
  35.   - custom background-image (3.x only)
  36.   - localized
  37.   - and more
  38. @endnode
  39. @node Requirements "TolleUhr Documentation - Requirements"
  40. Requirements
  41. ************
  42. TolleUhr requires at least v37 of the OS. The plain version will run on every
  43. 680x0, the other version requires a 68020 or higher. TolleUhr should work with
  44. gfx-cards. The same applies to the libraries. One last requirement: you need
  45. an Amiga (but this should be obvious :)
  46. The program has been tested on:
  47.   - an A1200, 68020,     WB3.0
  48.   - an A4000, 68030/882, WB3.0
  49.   - an A4000, 68030/882, WB3.0, Retina Z3
  50. @endnode
  51. @node Installation "TolleUhr Documentation - Installation"
  52. Installation
  53. ************
  54. You have to decide which kind of TolleUhr you want use. You can select between
  55. the normal one and the shared library.
  56. For the ordinary type only two files have to be copied (the program and its icon),
  57. so I do not provide an installation script. TolleUhr likes to be placed in the
  58. WBStartup drawer :-), but you can copy it to any location (preferable on a harddisk).
  59. The library version needs some more work: a library version has to be copied to
  60. a LIBS: location and `TuLoader' should go to the WBStartup drawer as `TolleUhr'.
  61.   Hint: If don't want TolleUhr reside on your system partion, you can place a
  62.         project in the WBStartup drawer with TolleUhr as default tool. This
  63.         technique can be used for any other program.
  64. Please select yourself a version that suits your needs and/or requirements. Both
  65. versions support the locale.library. A catalog for german can be found in the
  66. catalogs drawer. To install the catalog copy it to "LOCALE:catalogs/deutsch".
  67. Since both the asm and the c version are now pure I turned TU into a shared
  68. library. Why one will ask. Ok, the explanation:
  69.  Some time ago there was a discussion on comp.sys.amiga.programmers that making
  70.  programs resident is not a clever decision since that has to be done by hand
  71.  (also to remove the program later). A library has the advantage that the system
  72.  will handle this. If memory is needed the system will flush the library.
  73. @endnode
  74. @node Usage "TolleUhr Documentation - Usage"
  75. Usage
  76. *****
  77. TolleUhr can be started either from CLI/Shell or from the Workbench. Settings
  78. will always be saved to the programs icon (will be created if it doesn't exist).
  79. Sending a Ctrl-c to TolleUhr causes the program to abort immediately.
  80. Menus:
  81. ------
  82. You can set anything but pubscreen, taskpriority and background image from
  83. menus and save it to the tooltypes field with the `Save prefs' menu. There
  84. is also an alarm-function from menus.
  85. Gadgets:
  86. --------
  87. There is an invisible close-gadget in the upper left corner of the window,
  88. an (also invisible) depth-gadget in the upper right, a sizing-gadget in the
  89. lower right corner and a drag-gadget in the middle of the window.
  90. Background image:
  91. -----------------
  92. An image as window background is only available with OS3.x, since this feature
  93. uses the datatypes.library. You can use any image format as long as a datatype
  94. for the image type has been installed (and activated).
  95.   IMAGE    - name of a picture (including the path)
  96.   USEIMAGE - show the image
  97.   NOREMAP  - by default the 'picture.datatype' remaps a picture. This prevents
  98.              color remapping - check it out (seems to be useful for MagicWB 2.0)
  99. Please note, that this feature can need *much* memory! Window resizing will become
  100. very slow on a screen with many colors. This should affect only native graphics,
  101. not graphic cards.
  102. The arguments:
  103. --------------
  104.  Shell-Template: (for a short description see below at the tooltypes)
  105.  TOP/N,LEFT/N,WIDTH/N,HEIGHT/N,SECONDS/S,PATTERN/K,OVAL/S,SHADOW/S,SHOWFACE/N,
  106.  HANDTYPE/N,HANDWIDTH/N,DRAWPENS/K,BORDERTYPE/N,CHIME/N,CLOSEGAD/S,USEIMAGE/S,
  107.  NOREMAP/S,IMAGE/K,PUBSCREEN/K,TASKPRI/N:
  108.  Tooltypes:
  109.  TOP       - Number of Pixels in top of the window
  110.  LEFT      - Number of Pixels left of the window
  111.  WIDTH     - Width of the window in pixels
  112.  HEIGHT    - Height of the window in pixels
  113.  SECONDS   - 1: seconds on 0: seconds off
  114.  PATTERN   - 0000-3333
  115.  OVAL      - 1: oval face 0: rectangle
  116.  SHADOW    - 1: shadow on 0: shadow off
  117.  SHOWFACE  - 0: show minute marks 4: show no marks at all
  118.  HANDTYPE  - 0: line 1: triangle 2: rhombus 2: rectangle
  119.  HANDWIDTH - 0: very thin 4: very thick
  120.  DRAWPENS  - 00000000000000-33333333333333
  121.  BORDERTYPE- 0 no border 5 full border
  122.  CHIME     - 0 no chime 4 full functioning chime
  123.  CLOSEGAD  - activate the window close gadget
  124.  PUBSCREEN - Name of public screen
  125.  TASKPRI   - Priority of the clock-task (_should_ be between -5 and 5)
  126.  IMAGE     - name of a bitmap to be used as background
  127.  USEIMAGE  - display the image (if available)
  128.  NOREMAP   - disable color mapping
  129.  The background-pattern:
  130.  It is set by a decimal number of 4 digits (abcd) and gives a background-
  131.  pattern that looks like this:
  132.   abababababab  For example: 0110 gives dark grey
  133.   cdcdcdcdcdcd               0220 gives light grey
  134.   abababababab               0123 looks a bit like jeans-style
  135.   cdcdcdcdcdcd
  136.  numbers greater than nine are set as: xaabbccdd (hex)
  137.  The drawpens:
  138.  abcdefghijklmn
  139.  a color for second hand
  140.  b color for minute hand
  141.  c color for minute hand outline
  142.  d color for hour hand
  143.  e color for hour hand outline
  144.  f color for shadow
  145.  g color for 12'o clock mark
  146.  h color for quarters
  147.  i color for hour marks
  148.  j color for minute marks
  149.  k border color 0
  150.  l border color 1
  151.  m border color 2
  152.  n border color 3
  153.  You also can use xaabbccddeeffgghhiijjkkllmmnn.
  154. @endnode
  155. @node Bugs "TolleUhr Documentation - Known Bugs"
  156. Known Bugs
  157. **********
  158. Currently none :^)
  159. @endnode
  160. @node Source "TolleUhr Documentation - Technical stuff"
  161. TolleUhr exists as assembler and as C version. They differ only marginally:
  162.   The assembler version accepts DRAWPENS and PATTERN starting with '0x' or
  163.   '$', not only 'x'. (The C version will look a bit strangely with those
  164.    prefixes ;-) Furthermore the asm version is a little bit shorter :-)
  165. All other things work in both versions the same! A plain and a 68020 version
  166. is available (check the version strings).
  167. The C versions have been compiled with gcc (2.7.0 was used for the plain
  168. version and 2.3.3 for the 020). Since the new 1.3 version only gcc is able
  169. to compile the the program in its current form since it uses one feature
  170. not available with other compilers (AFAIK).
  171. (For the freaks: With gcc one can declare global register variables. TU uses
  172.                  such a variable to keep all variables `globally' visible that
  173.                  are needed by several functions and to give gcc `global'
  174.                  library bases. There is no other way to use structure elements
  175.                  as library bases with gcc's inlines in its current form. There
  176.                  exists a solution, but until now nobody created new inlines
  177.                  that would support this.
  178.                  With SAS/C there would be a better solution. There one would
  179.                  always simply pass the address of the "global structure" as
  180.                  the first function argument since SAS/C can use non-global
  181.                  library bases.)
  182. I used 2.7.0 and 2.3.3 to compile the clock. Since it doesn't need '-fbaserel'
  183. anymore one can use every other gcc version (I tested 2.6.3). The 'new' proto
  184. includes for gcc have to be installed (distributed since gcc 2.6.1). 
  185. The assembler version also comes in two flavors. Its my first try with 68020+
  186. instructions and I am not sure its worth the efforts. Anyway there is a version
  187. for 'bigger' processors. The source for this version is supplied as a diff-file,
  188. so you need a 'patch' program, eg. from the gcc-distribution :-). Additionally
  189. you need an assembler capable of handling 68020 instructions. I tested PhxAss but
  190. I used SNMA (a really good one, but only few people seem to use it) to create the
  191. 68020 executable. A68k (v2.71) is sufficient to create the plain version.
  192.  WARNING: SNMA 2.03 (8-Oct-95) *cannot* be used to assembler TU since it has
  193.           a bug with pc-relative addressing. So be careful!
  194. @endnode
  195. @node History "TolleUhr Documentation - History"
  196. History
  197. *******
  198. * 1.31: both:
  199.         - can now be turned into a shared library
  200.         asm:
  201.         - fixed some wrong comments in the source
  202.         c:
  203.         - completely rewritten to get almost the same structure as the asm
  204.           version (only 2k larger than the asm version!)
  205.         - does now also support catalogs (uses the same as the asm one)
  206.         - residentable without the help of a startup-code
  207. * 1.3 : both:
  208.         - changed window handling to shared IDCMP
  209.         - fixed low-memory bugs (eg. return value of BuildEasyRequest)
  210.         - added support for a background image via datatypes (OS3.x only!)
  211.         - better icon handling (if started from CLI)
  212.         - taskpriority now defaults to 0 (values >0 cause the mysterious
  213.           system 'hangs' - a v39 only problem !?)
  214.         asm:
  215.         - fixed alarmSet() - didn't set st/mi
  216.         - reduced overall stackusage
  217.         - savePrefs() rewritten
  218. * 1.21: both:
  219.         - window will now be opened with 'WA_AutoAdjust' (so the window
  220.           will open almost always)
  221.         asm:
  222.         - several minor improvements (can't remember exactly what)
  223.         - reduced stackusage
  224.         - tweaked :-)
  225.         c:
  226.         - removed a bug in saveprefs() that created blank lines
  227.         - some code cleanups
  228. * 1.12: - added NewLookMenus for OS3.x
  229.         - area buffer was to small
  230.         - assembler version created
  231. * 1.11: - initial release
  232. @endnode
  233. @node Acknowledgments "TolleUhr Documentation - Acknowledgments"
  234. Acknowledgments
  235. ***************
  236. Thanks to all who supplied suggestions for improvements, enhancements or showed
  237. general interest.
  238.   - Matthias Fleischer
  239.     for writing the original program and for libnix :^)
  240.   - Piere Carette &&  Walter Doerwald
  241.     for their ImageBackfill example, that showed me, how easy it is to use
  242.     the datatype.library and for the great "CopyTiledBitMap()" function
  243.   - Mario Cattaneo
  244.     for his suggestions and testing various intermediate versions
  245.   - Henryk Richter
  246.     for his interrest in the further development of TolleUhr
  247.   - Markus Wild
  248.     for porting gcc to the amiga (for -fbaserel I am using still his port of 2.3.3)
  249.   - Samu Nuojua
  250.     for his assembler SNMA (used to assemble the asm version)
  251. @endnode
  252. @node Disclaimer "TolleUhr Documentation - Disclaimer"
  253. Disclaimer
  254. **********
  255. Standard disclaimer:
  256. THERE IS NO WARRANTY FOR THE SOFTWARE TO THE EXTENT PERMITTED BY APPLICABLE
  257. LAW.  EXCEPT WHERE OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
  258. OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
  259. EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  260. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
  261. ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
  262. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  263. SERVICING, REPAIR OR CORRECTION.
  264. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
  265. ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE SOFTWARE
  266. AS PERMITTED BELOW, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
  267. SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
  268. INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
  269. DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES
  270. OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
  271. SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  272. DAMAGES.
  273. @endnode
  274. @node Copyright "TolleUhr Documentation - Copyright"
  275.  This program is public-domain, that means you can copy, modify or use it as
  276.  long as you wish and you needn't pay anything.
  277.  But: It must be absolutely clear at any time if and by what person this
  278.       program was modified - there must be a FULL list of ALL the authors
  279.       who made ANYTHING about this program at least in the source code
  280.       and also in any about-requesters.
  281. @endnode
  282. @node Author "TolleUhr Documentation - Author"
  283. Author
  284. ******
  285. To send suggestions, bug reports, comments, gifts, flames, etc., you can
  286. contact me at one of the following addresses:
  287.   email: gnikl@informatik.uni-rostock.de    (prefered)
  288.          or
  289.   snail: Gunther Nikl
  290.          Ziegendorfer Chaussee 96
  291.          Parchim
  292.          19370
  293.          GERMANY
  294. The first released version of this program was written by Matthias Fleischer.
  295.   email: fleischr@izfm.uni-stuttgart.de
  296.          or
  297.   snail: Matthias Fleischer
  298.          Adlerstra
  299.          73760 Ostfildern 2
  300.          GERMANY
  301. (don't ask _him_ for any enhancements, he dropped the development - G.N.)
  302. @endnode
  303.